- @title = 'Overlays'
:textile
  h3. Overlays
  
  The @Ojay.Overlay@ package provides a number of classes that help you to place content
  on top of the rest of the page. You can use these base classes to construct window systems,
  lightbox effects, and any number of other UIs. The @Overlay@ package is designed to
  be very general and highly flexible, and is based on the simple idea of positioning an
  HTML element absolutely on top of the page. The core classes are:
  
  * @Overlay@ - provides most of the API, but unlikely you'll use this directly
  * @ContentOverlay@ - for positioning content on top of the page, extends @Overlay@
  * @Tooltip@ - extends @ContentOverlay@ to provide overlays that follow the mouse
  * @PageMask@ - extends @Overlay@, can be used to 'fade out' the page for lightbox effects
  
  h3. Required files
  
  * @http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js@
  * @http://yui.yahooapis.com/2.5.2/build/selector/selector-beta.js@
  * @http://yui.yahooapis.com/2.5.2/build/animation/animation.js@
  * @http://yoursite.com/ojay/js-class.js@
  * @http://yoursite.com/ojay/core.js@
  * @http://yoursite.com/ojay/pkg/overlay.js@
  
  h3. Creating an overlay
  
  It is unlikely that you will use the @Overlay@ class directly - you will probably use
  one of its descendants instead. But since it contains most of the API for the other classes
  I will be using it to go through the methods available. Click 'Show me' after each bit of
  code to see it in action.
  
  To create an overlay, you pass in a set of options - the available options are listed
  in this example:
  
  <pre>
  var overlay = new Ojay.Overlay({
    width:      400,
    height:     300,
    left:       450,
    top:        1350,
    className:  'example',
    layer:      10,
    opacity:    0.7
  });</pre>
  
  This will add the following markup to the top of the @body@ element:
  
  <pre>
  <div class="overlay-container example"></div></pre>
  
  The element will be absolutely positioned and have the position and dimensions you
  specify. All the options are just that - optional; if you omit an option it's given
  a sensible default value.
  
  h3. Showing and hiding
  
  By default, overlays are not shown on creation. To show it, call its @show()@ method
  with the name of a transition effect. Available transitions are @fade@ and @zoom@; if
  you don't specify a transition, the overlay shows/hides instantaneously.
  
  <pre>
  overlay.show('fade');</pre>
  <div class="showme" id="sm1">Show me</div>
  
  That's probably getting in your way a bit there, so let's hide it again:
  
  <pre>
  overlay.hide('zoom');</pre>
  <div class="showme" id="sm2">Show me</div>
  
  They are even chainable using @MethodChain@:
  
  <pre>
  overlay.show('zoom').wait(3).hide('fade');</pre>
  <div class="showme" id="sm3">Show me</div>
  
  h3. Positioning methods
  
  To set the position of an overlay, you can use its @setPosition()@ method, if you want
  to center the overlay on the screen call @center()@:
  
  <pre>
  overlay.setPosition(600, 1500);</pre>
  <div class="showme" id="sm4">Show me</div>
  
  <pre>
  overlay.center();</pre>
  <div class="showme" id="sm5">Show me</div>
  
  As well as horizontal/vertical positioning, @Overlay@ makes z-positioning easy. The following
  methods can be used to set the z-index of an overlay:
  
  * @overlay.setLayer(n)@ - sets the overlay's z-index to @n@
  * @overlay.positionBehind(another)@ sets the overlay's z-index so it displays behind @another@ overlay
  * @overlay.positionInFront(another)@ sets the overlay's z-index so it displays in front of @another@ overlay
  
  h3. Sizing methods
  
  To set the size of an overlay, just pass in the width and height values. These can be numbers,
  or strings containing units. If numbers are used, we assume the units are pixels:
  
  <pre>
  overlay.setSize('25%', '10%');
  overlay.center();</pre>
  <div class="showme" id="sm6">Show me</div>
  
  <pre>
  overlay.setSize(400, 200);
  overlay.center();</pre>
  <div class="showme" id="sm7">Show me</div>
  
  h3. Getting size and position information
  
  There are a number of methods for getting information about the size and position of an
  overlay. These are @getSize()@, @getPosition()@ and @getRegion()@.
  
  <pre>
  var pos = overlay.getPosition(), size = overlay.getSize();
  alert('Left: ' + pos.left + ', top: ' + pos.top);
  alert('Width: ' + size.width + ', height: ' + size.height);
  alert(overlay.getRegion().toString());</pre>
  <div class="showme" id="sm8">Show me</div>
  
  If you want to know the z-index of an overlay, just call @overlay.getLayer()@.
  
  h3. Changing the opacity
  
  Setting and getting the opacity of an overlay is straightforward with the following methods:
  
  <pre>
  overlay.center();
  alert(overlay.getOpacity());
  overlay.setOpacity(0.3);</pre>
  <div class="showme" id="sm9">Show me</div>
  
  h3. Listening to events
  
  All @Overlay@ instances (and instances of its subclasses) publish a number of events that you
  can listen and react to. These events are:
  
  * @show@ - fired when an overlay is made visible
  * @hide@ - fired when an overlay is hidden
  * @close@ - fired when the overlay is removed from the DOM
  
  To listen to one of these events, just use the @on()@ method. The overlay instance is
  passed as the first argument to your callback.
  
  <pre>
  var overlay = new Ojay.Overlay();
  
  overlay.on('show', function(overlay) {
    // do other stuff with overlay,
    // call other parts of your codebase
  });</pre>
  
  h3. Using @ContentOverlay@
  
  This is likely to be the overlay type you'll use most often. It has all the methods we've
  discussed so far, plus a few more to let you populate the overlay with HTML content. You
  create a content overlay in much the same way as above, but you can pass an extra option,
  @content@ to set the initial content.
  
  <pre>
  var overlay = new Ojay.ContentOverlay({
    /* standard options here */
    content: '<h1>The title</h1><p>The content</p>'
  });</pre>
  
  The markup generated is slightly different to that of basic @Overlay@ instances, and looks
  like the following:
  
  <pre>
  <div class="overlay-container">
      <div class="overlay-content">
          <h1>The title</h1>
          <p>The content</p>
      </div>
  </div></pre>
  
  @ContentOverlay@ instances have two extra methods on top of those provided by @Overlay@:
  @setContent()@ and @insert()@. These work in exactly the same way as the methods of the
  same names found in the Ojay core library, and simply manipulate the contents of the
  @overlay-content@ element. They also have a @fitToContent()@ method, which sizes the overlay
  container element so that it only just contains the content element.
  
  h3. Using @PageMask@
  
  The @PageMask@ class extends @Overlay@ and provides a mechanism for fading out page
  content to create a 'lightbox' effect. As an example, let's fetch some content using Ajax
  and display it in a lightbox above the page (push ESC to close the overlay):
  
  <pre>
  var mask = new Ojay.PageMask({color: '#807065', opacity: 0.8});
  var overlay = new Ojay.ContentOverlay({className: 'ex1'});
  mask.positionBehind(overlay);
  
  Ojay.HTTP.GET('/service/paginator/01.html')
  .insertInto(overlay)
  ._(mask).show('fade')
  ._(overlay).fitToContent().center().show('zoom');
  
  Ojay.Keyboard.listen(document, 'ESCAPE', function() {
    overlay.hide('zoom')._(mask).hide('fade');
  });</pre>
  <div class="showme" id="sm10">Show me</div>
  
:plain
  <style type="text/css">
    .example { background : #000; }
    .showme { cursor: pointer; background: #807065; color: #fff; font-size: 10px; font-weight: bold; width: 48px; padding: 2px 4px; margin-top: 0; }
    pre { margin-bottom: 0; }
    .ex1 .overlay-content { border: 2px solid #C2ECE7; background: #fff; padding: 0 20px; }
  </style>
  
  <script type="text/javascript">
    var overlay = new Ojay.Overlay({
      width:      400,
      height:     300,
      left:       450,
      top:        1350,
      className:  'example',
      layer:      10,
      opacity:    0.7
    });
    
    Ojay('#sm1').on('click')._(overlay).show('fade');
    Ojay('#sm2').on('click')._(overlay).hide('zoom');
    Ojay('#sm3').on('click')._(overlay).show('zoom').wait(3).hide('fade');
    Ojay('#sm4').on('click')._(overlay).setPosition(600, 1500);
    Ojay('#sm5').on('click')._(overlay).center();
    Ojay('#sm6').on('click')._(overlay).setSize('25%', '10%').center();
    Ojay('#sm7').on('click')._(overlay).setSize(400, 200).center();
    
    Ojay('#sm8').on('click', function() {
      var pos = overlay.getPosition(), size = overlay.getSize();
      alert('Left: ' + pos.left + ', top: ' + pos.top);
      alert('Width: ' + size.width + ', height: ' + size.height);
      alert(overlay.getRegion().toString());
    });
    
    Ojay('#sm9').on('click', function() {
      overlay.center();
      alert(overlay.getOpacity());
      overlay.setOpacity(0.3);
    });
    
    Ojay('#sm10').on('click', function() {
      var mask = new Ojay.PageMask({color: '#807065', opacity: 0.8});
      var overlay = new Ojay.ContentOverlay({className: 'ex1'});
      mask.positionBehind(overlay);
      
      Ojay.HTTP.GET('/service/paginator/01.html')
      .insertInto(overlay)
      ._(mask).show('fade')
      ._(overlay).fitToContent().center().show('zoom');
      
      Ojay.Keyboard.listen(document, 'ESCAPE', function() {
        overlay.hide('zoom')._(mask).hide('fade');
      });
    });
  </script>
